home *** CD-ROM | disk | FTP | other *** search
/ Linux Cubed Series 3: Developer Tools / Linux Cubed Series 3 - Developer Tools.iso / utils / text / yodl.rea < prev   
Encoding:
Text File  |  1996-11-16  |  6.8 KB  |  145 lines
  1.  
  2. ===============================================================================
  3.  
  4.                    Y O D L
  5.             Yet Oneother Document Language
  6.  
  7.                Karel Kubat (karel@icce.rug.nl)
  8.  
  9. ===============================================================================
  10.  
  11. YODL (Yet Oneother Document Language) is a package that consists of programs,
  12. some shell scripts, and auxiliary "lib" files for one of the programs. The
  13. whole purpose of the package is to provide a simple-to-use and extensible
  14. document language, that can be used to convert documents in the YODL format to
  15. a variety of other formats. In this purpose, YODL somewhat resembles generic
  16. markup languages (e.g. SGML), but:
  17.  
  18.     - YODL is easier to use. Well I find so. 
  19.     
  20.     - YODL is very well documented. That my version of SGML isn't is, I guess, 
  21.       no fault of SGML, but I had a _very_ hard time getting SGML to do what I 
  22.       wanted it to do! Well, YODL should be easier to handle. The docs include
  23.       various manpages and a more than 50 pages DIN A4 document.
  24.  
  25.     - YODL doesn't insist on weird tags. YODL is not a markup language in that
  26.       sense (starting and ending tags), YODL handles all its commands in a
  27.       C-style manner; e.g. em(text) will set the text emphasized. Similarly,
  28.       macros can have two arguments or more, also all in a parameter-list
  29.       format. This is more of an advantage than you might think at first
  30.       glance: e.g., my editor won't match a closing tag in HTML with the
  31.       opening tag, but it _will_ show the open-parenthesis when I type a
  32.       closing parenthesis!
  33.       
  34.     - YODL has support for conditional processing: by testing for some symbol, 
  35.       or say for the presence of an argument, you can do different things in a 
  36.       macro. Or you can redefine macros, and the such.
  37.  
  38. Currently the package supports conversions to LaTeX, HTML, to the "man"
  39. format, and poor-mans conversions to plain ASCII and SGML (for compatibility
  40. reasons at our site).  Other conversions are of course possible, but these are
  41. the formats that I use and why I wrote YODL in the first place.
  42.  
  43. If you want to obtain YODL and try it out, ftp to
  44. ftp://ftp.icce.rug.nl/pub/unix/ and look for a file yodl-X.YY.tar.gz, with
  45. X.YY being a version number (0.00 is of course the first). Unpack it in a
  46. "sources" directory and type "make htmldoc" or "make latexdoc" and see for
  47. yourself...
  48.  
  49. YODL has evolved from the previous DOM package, that I developed but didn't 
  50. distribute yet. DOM used to be "DOcument Maintainer", but I don't think that 
  51. the nomenclature was too good. Besides, I can now use ".yo" for file
  52. extensions.
  53.  
  54. YODL is currently beta-state, that means that it may not be very complete (but
  55. I'm working on it), that there may be bugs in it (not that I know of), and
  56. that new versions may arrive quickly.  Yes, I am looking for testers! If
  57. you're interested, get YODL and mail me what you think. 
  58.  
  59. Just for fun, here's a piece of a YODL file. Not that you should carefully read 
  60. it, it's just to give you an idea of the YODL language.
  61.  
  62. ------------------------------------------------------------------------------
  63. The tt(yodl) program is reads one or more input files, interprets the commands 
  64. therein, and writes one output file. The program is started as:
  65.  
  66. center(
  67.     tt(yodl) em(flags) em(inputfile) em([inputfile...])
  68. )
  69.  
  70. In this specification, the flags are optional and may be:
  71.  
  72. itemize(
  73.     
  74.     it() tt(-D) em(name): Defines em(name) as a symbol. This flag is similar 
  75.     to the tt(DEFINESYMBOL) statement which may appear in the text. The 
  76.     purpose of defining symbols is described later.
  77.     
  78.     it() tt(-I) em(directory): This defines the system-wide include directory 
  79.     where tt(yodl) searches for its input files when they cannot be located 
  80.     by their bare name. E.g. a statement to include a given file:
  81.     
  82.     verb(INCLUDEFILE(latex))
  83.     
  84.     will search for the file tt(latex) in the current directory, and when that 
  85.     fails, in the system-wide include directory. The system-wide include 
  86.     directory is typically the place where the maintainer of a system stores 
  87.     macro-files for YODL. This searching process applies to files that are 
  88.     included inside a document but also applies to filenames on the command 
  89.     line when invoking the tt(yodl) program.
  90.     
  91.     The name of the included file (tt(latex) in the above example) is the 
  92.     bare name, the tt(yodl) program will supply a default extension if 
  93.     necessary. 
  94.     
  95.     The tt(-I) flag overrules YODL's built-in name for the system-wide include 
  96.     directory. The built-in name is defined when compiling YODL, and is usually 
  97.     tt(/usr/local/lib/yodl). 
  98.     
  99.     it() tt(-k): This flag causes YODL to keep the intermediate parsing files, 
  100.     instead of removing them. The intermediate files are usually located in 
  101.     the directory tt(/tmp) and named something like tt(yodl1254.4), where the 
  102.     numbers indicate the process number of the YODL run (1254) and the ordinal 
  103.     number of the parsing run (4). Using this flag is usually only good for 
  104.     debugging purposes.
  105.     
  106.     it() tt(-o) em(file): This option causes YODL to write its output to em(
  107.     file). By default, the output goes to the standard output stream. E.g., 
  108.     you can use the tt(yodl) program to read a file tt(input) and to write to 
  109.     tt(output) with the following two commands:
  110.     
  111. verb(\
  112. yodl input > output
  113. yodl -ooutput input)
  114.     
  115.     it() tt(-p) em(maxpass): This flag causes YODL to abort when the number of 
  116.     parsing cycles exceeds em(maxpass), which is usually 20. Exceeding this 
  117.     number usually means a circular definition somewhere in the document. This 
  118.     is the case when, e.g., a macro tt(a) expands to tt(b), and tt(b) expands 
  119.     again to tt(a).
  120.     
  121.     it() tt(-t): This flag enables tracing: while parsing, YODL writes its 
  122.     output to the standard error stream. As is the case with the tt(-k) flag, 
  123.     this option is for debugging purposes.
  124.     
  125.     it() tt(-v): This flag increases YODL's `verbosity level' and may occur 
  126.     more than once. The presence of one tt(-v) causes YODL to show which files 
  127.     are parsed; four tt(-v)'s show the inner workings of YODL's lexical 
  128.     analyzer. 
  129.     
  130.     it() tt(-w): The presence of this flag caused YODL to warn when, e.g., 
  131.     symbols are redefined.
  132. )
  133.  
  134. The em(inputfile) elements on the command line specify which files YODL should 
  135. process. All names are supplied with an extension+footnote(this extension is 
  136. defined in the installation of YODL and is usually .yo). The files are then 
  137. searched for `as-is', or in the system-wide include directory.
  138.  
  139. Note that all filenames on the command line are input files. To 
  140. define an output file, either use the tt(-o) flag or redirect the output. 
  141. ------------------------------------------------------------------------------
  142.  
  143. That's all for now. Hope that I have tickled your curiosity..
  144. Karel.
  145.